<!DOCTYPE html>
<!--
Copyright 2017 The Chromium Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.
-->

<link rel="import" href="/tracing/extras/chrome/cpu_time.html">
<link rel="import" href="/tracing/metrics/metric_registry.html">
<link rel="import" href="/tracing/metrics/system_health/cpu_time_tree_data_reporter.html">
<link rel="import" href="/tracing/value/histogram.html">

<script>
'use strict';

/**
 * @fileoverview Implements the new CPU time metric. This will eventually
 * replace the current cpu_time_metric.html, but we're running this alongside
 * the existing metric while we monitor its quality.
 *
 */
tr.exportTo('tr.metrics.sh', function() {
  /**
   * This metric measures total CPU time and CPU time per unit of wall clock
   * time for all combinations of process type, thread type, RAIL
   * stage, and RAIL stage initiator present in the model.
   *
   * The metric generates histograms of the form
   *   ${cpuTime|cpuPercentage}:${process_type}:${thread_type}:
   *   ${rail_stage}:${rail_stage_initiator}
   *
   * 'cpuTime' histograms represent total consumed CPU time, while
   * 'cpuPercentage' histograms represent CPU time as a percentage of wall clock
   * time.
   *
   * Example histograms generated by this metric:
   * - cpuTime:browser_process:CrBrowserMain:Animation:CSS
   * - cpuPercentage:gpu_process:CrGpuMain:Response:Scroll

   * For a given model, a single sample is generated for each histogram. For
   * example, if the model contains three renderer processes, and 10 different
   * Scroll Response ranges, the histogram
   * cpuPercentage:renderer_process:CrRendererMain:Response:Scroll will still
   * contain a single sample: the total CPU time consumed by all three renderer
   * main threads over all 10 Scroll Response phases, divided by the total
   * duration of those ranges. Since the three different main threads can
   * potentially be running on three different CPU cores, the sample value of a
   * cpuPercentage histogram can be more than 100%.
   *
   * The histograms are created as needed from the model - if a certain
   * combination of process, thread, RAIL stage and initiator does not occur in
   * the model, the histogram for that combination is not added.
   *
   * This metric requires only the 'toplevel' tracing category.
   *
   * @param {!tr.v.HistogramSet} histograms
   * @param {!tr.model.Model} model
   * @param {!Object=} opt_options
   */
  function newCpuTimeMetric(histograms, model, opt_options) {
    const rangeOfInterest = opt_options && opt_options.rangeOfInterest ?
      opt_options.rangeOfInterest : model.bounds;

    const rootNode = tr.e.chrome.CpuTime.constructMultiDimensionalView(
        model, rangeOfInterest);

    tr.metrics.sh.CpuTimeTreeDataReporter.reportToHistogramSet(
        rootNode, histograms);
  }

  tr.metrics.MetricRegistry.register(newCpuTimeMetric, {
    supportsRangeOfInterest: true
  });

  return {
    newCpuTimeMetric,
  };
});
</script>
